Freeze released isolated sessions and project markers (#271) - #291

Refs #271. This is the Sessions and project family. It follows the convention of the artifacts, rooms and workflows families. The issue stays open.

What

• Generator. tests/fixtures/persisted/sessions/freeze.py writes the fixtures for v0.1.2, v0.2.0 and v0.3.0, each with the release's own CLI.
  • It runs the release's syncmill init. The marker stays untracked and ignored, and syncmill.toml is committed.
  • It then runs session open codex --no-attach against a fake interactive codex in a real tmux.
  • A tmux on the fake PATH execs the real binary with a private socket and no config, so the user's server is never touched.
  • The private server is stopped and proved gone before the box is removed. If that cannot be proved, nothing is removed and the run exits nonzero.
• Scenarios (per release):
  • project: syncmill.toml plus the marker directory's project.json and .gitignore, stored as marker.json and marker.gitignore. From v0.2.0, init's .gitignore names project.json itself, so Git would ignore the marker under its own name. Its 0600 mode is asserted and recorded.
  • open; checkpointed, with one checkpoint run artifact; closed.
  • creating, closing, recovery-required, from a .pth hook loaded for the run only: an exit on entry to the tmux launch, an exit right after the closing document, and a cleanup that reports failure.
  • Workspaces are not frozen: they are Git repositories holding absolute paths.
• Rebinding. Each session document's four paths and its fingerprint (kept in its released v1 version) are rebound, and the checkpoint manifest's root and fingerprint, with exact counts. Every other field is asserted unchanged; the tmux name re-derives. tmux is never launched in a test.
• Readers:
  • session isolated-list (liveness from the probe, staleness in the stored version, open sessions only) and render_session.
  • The path binding: a document under another workspace root, with another tmux name, a worktree outside its run root, or another repository is skipped by list and refused by checkpoint.
  • attach-isolated: refused when the session is not running or a pane is elsewhere, attached to the one right pane, and refused from every non-open state.
  • checkpoint without its worktree.
  • close of every state with the workspace gone: each ends closed at a pinned revision, and a closed one is returned unchanged.
  • The checkpoint artifact:
    • read through runs list / show, diff, and conversations show / list / close;
    • continue refused (no provider session), and recover skipped;
    • apply (left applied with its receipt bound) and validate_applicable;
    • discard, and prune, which keeps it while pending and removes it once discarded;
    • the TUI's render_artifact and _read_artifact_result.
  • The project:
    • project_id with the released marker untracked (its id), and tracked or symlinked (the path hash);
    • load_project_config of the released config, value for value;
    • initialize_project falling back to the marker.
• docs/architecture/persisted-contracts.md: the row names these. Not covered: a successful checkpoint or worktree cleanup, because a release-written workspace is not relocatable.

No source under src/ changes. No current reader misread a released session or marker.

Verification

• suite-run CLEAN; ruff check . clean.
• 16 injected regressions in isolated_session.py, project.py, artifacts.py and worktree.py each fail an intended assertion. They include:
  • each path or name binding removed;
  • liveness or staleness ignored;
  • the pane, state and missing-worktree checks removed;
  • close not idempotent;
  • each marker gate removed, and the re-init fallback dropped;
  • pending prune allowed;
  • the fingerprint recomputed in the current version;
  • the applied flip skipped.
• The generator's shutdown-failure path was exercised with the shutdown reported as failed: it kept the box and socket and exited nonzero. That leftover was then removed by hand, after confirming the server was down.
• Codex reviewed the design in two rounds before approval. The implementation went three rounds:
  • Round 1: NEEDS-FIX, fixed in 56535a0.
    • The fingerprint version and the applied state were unchecked.
    • Generator cleanup ran in the wrong order.
    • Release discovery picked up __pycache__.
  • Round 2: NEEDS-FIX, fixed in 1eacaf9.
    • Round 1's cleanup fix still deleted the box on failure.
    • Two config values were unchecked.
    • One timestamp assertion depended on the clock.
  • Round 3: unprimed, given the diff only. SHIP with no findings.

🤖 Generated with Claude Code